{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"contentcontainer med left\" style=\"margin-left: -50px;\">\n",
    "<dl class=\"dl-horizontal\">\n",
    "  <dt>Title</dt> <dd> Labels Element</dd>\n",
    "  <dt>Dependencies</dt> <dd>Matplotlib</dd>\n",
    "  <dt>Backends</dt> <dd><a href='./Labels.ipynb'>Matplotlib</a></dd> <dd><a href='../bokeh/Labels.ipynb'>Bokeh</a></dd>\n",
    "</dl>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import holoviews as hv\n",
    "from holoviews import opts\n",
    "\n",
    "hv.extension('matplotlib')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ``Labels`` element may be used to annotate a plot with a number of labels. Unlike the ``Text`` element, ``Labels`` is vectorized and allows plotting many labels at once. It also supports any [tabular](../../../user_guide/08-Tabular_Datasets.ipynb) or [gridded](../../../user_guide/09-Gridded_Datasets.ipynb) data format. This also means that most other elements may be cast to a ``Labels`` element to annotate or label the values.\n",
    "\n",
    "``Labels`` also support various options that make it convenient to use as an annotation, e.g. ``xoffset`` and ``yoffset`` options allow adjusting the position of the labels relative to an existing data point and the ``color`` option allows us to colormap the data by a certain dimension."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.random.seed(9)\n",
    "data = np.random.rand(10, 2)\n",
    "points = hv.Points(data)\n",
    "labels = hv.Labels({('x', 'y'): data, 'text': [chr(65+i) for i in range(10)]}, ['x', 'y'], 'text')\n",
    "\n",
    "(points* labels).opts(\n",
    "    opts.Labels(color='text', cmap='Category20', xoffset=0.05, yoffset=0.05, size=14, padding=0.2),\n",
    "    opts.Points(color='black', s=25))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the value dimension of the data is not already of string type it will be formatted using the applicable entry in ``Dimension.type_formatters`` or an explicit ``value_format`` defined on the Dimension. Additionally the ``color_index`` option allows us to colormap the text by a dimension.\n",
    "\n",
    "Here we will create a 2D array of values, define a Dimension with a formatter and then colormap the text:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "value_dimension = hv.Dimension('Values', value_format=lambda x: '%.1f' % x)\n",
    "xs = ys = np.linspace(-2.5, 2.5, 25)\n",
    "zs = np.sin(xs**2)*np.sin(ys**2)[:, np.newaxis]\n",
    "\n",
    "hv.Labels((xs, ys, zs), vdims=value_dimension).opts(\n",
    "    opts.Labels(bgcolor='black', cmap='viridis', color='Values', fig_size=200, padding=0.05, size=8))"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
